Tools Plus is a set of powerful “GUI Building/Event Managing” libraries for Macintosh programmers using any of the following compilers:
• Symantec Corporation’s THINK C or Symantec C/C++
• Symantec Corporation’s THINK Pascal
• Metrowerks CodeWarrior C/C++ and CodeWarrior Pascal
(for 680x0 and PowerPC processors)
Your specific developer kit includes only those libraries you selected when you bought Tools Plus.
Over 170 high-powered “set and forget” routines let you easily create your application’s user interface, while Tools Plus maintains it for you and takes care of event management.
In spite of its power and robust features, Tools Plus is easy to learn and easy to use, making it ideal for novices, intermediate developers, and experts.
With Tools Plus, you have the advantage of enhanced functionality, automation, and full integration of: windows, floating palettes, tool bar, cursors, buttons, picture buttons, scroll bars, editing fields, list boxes, pull-down and hierarchical menus, pop-up menus, the Edit menu, clipboard, alerts, event handling, and more. Once you create your user interface with Tools Plus’ routines, Tools Plus makes it work. Virtually all Tools Plus routines can be executed with a single line of code.
Using Tools Plus simplifies your programming and accelerates development. You’ll create applications in less time, with less source code, with far fewer bugs, and with more features than if you use ordinary C/C++ or Pascal.
Tools Plus libraries can be compiled into applications intended for System 5 and 6 (running under Finder and MultiFinder), System 7, and on the PowerPC (in emulated or native mode).
An Overview of Tools Plus
`````````````````````````
To describe Tools Plus in a single sentence, it’s a “user interface builder/maintainer, and event manager.” Its main function is to let you create a user interface without actually having to maintain it. A simple example of this is the Apple menu. With Tools Plus, you can give your application full reign over desk accessories just by creating the Apple menu with the AppleMenu routine. Tools Plus automatically takes care of any activity pertaining to desk accessories, such as when the user selects a desk accessory from the Apple menu, repositions the accessory by dragging it, clicks buttons or types in the accessory, copies and pastes text in the desk accessory, and eventually closes it. All this is handled automatically by Tools Plus (you don’t have to write any code for it).
The thing that makes all this possible is Components: every routine in the Tools Plus libraries is a reusable, self-contained, and self-maintaining Component designed to be an integral part of your application. Each Tools Plus Component is fully integrated with other Tools Plus Components, and with the Macintosh environment.
The majority of Tools Plus’s routines are dedicated to creating and accessing elements of your application’s user interface, such as a push-button, an editing field or a picture button. Once you have created a user interface element, you can forget about it. Tools Plus takes care of the rest. You can write your application using either Object Oriented Programming (OOP) or procedural (traditional) coding techniques.
Tools Plus’s features integrate with each other according to the User Interface guidelines found in Inside Macintosh. An active editing field, for example, automatically intercepts and processes key-strokes from the keyboard. An editing field’s text can also be affected by the Edit menu, which lets the user Cut, Copy, Paste, and Clear the text, as well as transfer text between your application and other applications and desk accessories via the clipboard. The Edit menu is automatically updated by the user’s actions in the active editing field: when an insertion point is in the field, the Edit menu’s “Cut” and “Copy” selections are disabled, since no text is selected for cutting or copying. You can see how this frees you (the programmer) to do more important things, like writing programs!
Not a Code Generator or Class Library
`````````````````````````````````````
Tools Plus differs in many ways from code generators and class libraries (for object oriented programming). It addresses the need to enhance productivity without inheriting the shortcomings if its predecessors. Class libraries, although incredibly powerful and versatile, demand that you make a heavy investment in time to learn the libraries before you become proficient with them. Tools Plus, on the other hand, is easy to learn. Code generators do just that: they generate code. Even though you don’t have to write the code yourself, you will inevitably have to understand the inner workings of that code. Tools Plus libraries eliminate the need for thousands of lines of code, thereby making your application simpler and easier to maintain
The heart-beat of Tools Plus is the polling routine, which is called by your application (instead of calling the Macintosh toolbox’s GetNextEvent or WaitNextEvent) to obtain events generated by the user, such as typing or mouse-clicks. In fact, all events are obtained this way. The big difference here is that Tools Plus’s polling routine does everything it possibly can before informing your application of an event. Many events are processed internally and are never reported to your application, such as when the user types in an Editing Field (because the field automatically processes the typing). Other events are reported to your application, such as when the user clicks a button.
In contrast to other polling routines such as GetNextEvent or WaitNextEvent, Tools Plus’s polling routine translates the Macintosh’s events into something your application can use right away. So instead of getting a low level “mouse down” event, your application gets a highly informative Tools Plus event such as: the “Save” button was selected in the “Add Customer” window (or button 4 was selected in window 15).
The following example illustrates the difference between ordinary C or Pascal programming, and a program written with Tools Plus. The left column represents the steps a traditional program has to take to detect and process a simple event, whereas the right column has the benefit of Tools Plus. Note that the left column is highly simplified!
Ordinary C or Pascal Programming Programming with Tools Plus
2 Determine the type of event (a = Button Selected event
“mouse-down”) (button 3 in window 15)
3 Determine its location (a
window’s content region)
4 Determine where in the window (a
“control”)
5 Track the mouse in and out of the
control
6 If the mouse button was released
inside the control’s region,
report that the control was
selected. Otherwise ignore the
entire event.
-----------------------------------
= Mouse-down event
in a control (handle is known)
in a window (pointer is known)
Of course, additional steps could be taken in traditional C or Pascal to obtain a window number and button number, but at the expense of more programming.
Who can benefit from Tools Plus
```````````````````````````````
Just about anybody writing an application on the Macintosh in C/C++ or can benefit from using Tools Plus. It’s useful to different people for different reasons:
• Novice programmers can start developing applications more readily and
with greater confidence. The task of programming is simplified to
produce quicker results with fewer bugs. And you don’t have to learn
a resource editor (such as Apple’s ResEdit) before you start using
Tools Plus.
• Seasoned programmers can use Tools Plus to develop an application in
less time and with fewer bugs.
What kind of applications can be written with Tools Plus
Tools Plus does not limit you to writing certain kinds of applications, in that it does not preclude you from exercising your technical or creative skills on the Macintosh. It merely helps simplify and manage the user interface and event processing that is so prevalent in Macintosh programs. Varying programming needs are addressed by Tools Plus:
• Quick and Dirty applications can be written in less time. These
programs can have all the features of finished Macintosh applications,
which makes them easier to work with.
• Full fledged applications that are suitable for shrink-wrapping can be
created using Tools Plus.
• Just about any program can be written more quickly and with less
effort by using Tools Plus.
What is Tools Plus not suitable for
```````````````````````````````````
Tools Plus is intended for application developers. It was designed to be the event processing and translating engine within an application, so it definitely cannot be used to create the following:
• Drivers, control panels, INITs or system extensions
• CODE segments that can be incorporated into other applications, such
as 4th Dimension
• Desk accessories. You can still use Tools Plus to write an
application that looks and feels like a desk accessory while running
under System 7.
System Requirements
```````````````````
Computer
````````
Tools Plus makes extensive use of ROM routines that are found only in the 128k ROMs (version 117) or higher. Applications written with Tools Plus will run on the Macintosh 512KE (the “E” stands for enhanced with the new ROMs) or higher. They will not run on a Lisa (also called a Macintosh XL), Macintosh 128K or a standard Macintosh 512K computer. These applications will also run on Power Macintoshes.
Compiler
````````
Tools Plus can be used by programmers developing with:
THINK C 5.0.4 or later
Symantec C/C++ 6.0.1 or later
Symantec C/C++ 7.0 or later
THINK Pascal 4.0.2 or later
CodeWarrior C/C++ 1.2.1 (68K or PPC) from the CW6 CD or later
CodeWarrior Pascal 950331 (68K or PPC) from the CW6 CD or later
Development Tools
`````````````````
Every Macintosh developer should have a copy of ResEdit, Apple’s resource editor application. It’s easy to use, indispensable, and best of all, free from your Apple dealer. Always get the latest version (2.1.3 at this writing), since it’s always being upgraded and improved. Beginners can get by without ResEdit, but you won’t want to.
System
``````
Applications created with Tools Plus can run under System 5, System 6 and System 7. We recommend you use at least System 6 (optimally 6.0.8) or System 7 because Apple has fixed various bugs and many features have been added to the newer versions of the system.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 and THINK Pascal 4.0 both require 2MB of RAM when using System 7. CodeWarrior requires System 7 or higher. Consult your compiler’s User Manual for details.
Memory
``````
Applications created with Tools Plus can run with less than 100k, depending on the complexity of your application. The overhead associated with Tools Plus is in the neighborhood of 75k for 680x0 libraries and slightly higher for PowerPC native libraries.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 and THINK Pascal 4.0 both require 2MB of RAM when using System 7. CodeWarrior requires 8MB. Consult your compiler’s User Manual for details.
Disk Space
``````````
Tools Plus libraries and related files require only a few hundred K of disk space. When compiled, Tools Plus libraries add about 75k to your 680x0 application’s size, and about 120k to your PPC application’s size (add both 680x0 and PPC for fat binary applications).
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 and THINK Pascal 4.0 both require about 2MB of disk space.
Finished Applications
`````````````````````
Please be aware that you, as a programmer, have the capacity to write applications that have requirements far in excess of Tools Plus’s minimum system requirements. It’s possible that you may choose to write a program that requires a math co-processor, System 7, 20 megabytes of RAM, and a pair of 20 inch color monitors. Be aware that your finished application will likely have needs that exceed Tools Plus’s minimum requirements.
Assumptions made when writing this manual
`````````````````````````````````````````
Several assumptions have been made when writing this manual:
• You are already a C, C++ or Pascal programmer, or are learning to be
one on your own. This manual does not teach you how to program in C
or Pascal, nor does it teach you how to use the Macintosh’s toolbox
routines. It merely teaches you how to use Tools Plus.
• This manual makes no attempt to teach you how to use THINK C/C++,
THINK Pascal, CodeWarrior C/C++ or CodeWarrior Pascal. Please consult
your User Manual in such matters, or contact the manufacturer of your
compiler.
• This manual makes no attempt to teach you how to use ResEdit, or any
other application or tool that is part of your development
environment.
• You already know how to use the Macintosh, and are familiar with its
terms such as clicking, dragging, selecting, etc.
• This manual does not assume that all programmers and users are male.
For the sake of easier reading, the term “he” implies either gender
within this manual.
Conventions used throughout this manual
```````````````````````````````````````
1) Each Tools Plus routine is documented with both a C header and
Pascal interface.
2) Source code examples are given in Pascal, just like Inside
Macintosh. In situations where the C source code differs (usually
due to differences in record structure), an example is also provided
in C.
3) The Pascal terms function and procedure are used throughout this
manual. For the benefit of C programmers, a function is a routine
that returns a value. The following table provides an example:
C “Procedure”: pascal void DeleteListBox(short ListBox);
Pascal Function : function FirstWindowNumber: integer;
C “Function” : pascal short FirstWindowNumber(void);
4) Important information is highlighted with notes and warnings...
Note: A note that may be interesting or useful (don’t skip these)
Warning: A point you need to be cautious about.
5) This manual is not intended to replace Inside Macintosh or its
equivalent. It does not detail the fundamentals of Macintosh
programming, such as screen versus window co-ordinate systems (local
versus global), commonly used structures (points, rectangles,
grafPort, etc.), using the Macintosh toolbox, etc.
6) For the benefit of new programmers, portions of this manual address
the basics of building a Macintosh application, such as some
differences between Finder and MultiFinder and how to complete a
double-clickable application.
Software Updates
````````````````
Registered Tools Plus users are entitled to take advantage of our Software Update Program, which offers free updates as well as updates at reduced prices. We recommend that you periodically check the Water’s Edge Software bulletin board on CompuServe (see the Technical Support chapter for details) to determine the latest version and information on how to upgrade.
Water’s Edge Software is enhancing Tools Plus on an on-going basis by optimizing code and adding new features. We will inform registered users of newly available updates either by mail or by electronic mail (if you provide us your e-mail account number, we will send you update information electronically).
Note: In order to ensure uninterrupted software update notification,
please inform us if your mailing address or e-mail account
changes.
Your Development Environment
````````````````````````````
This manual makes no attempt to teach you how to use your development environment, THINK C/C++ or THINK Pascal. Please consult your THINK C/C++ or THINK Pascal User Manual in such matters, or contact the manufacturer, Symantec Corporation.
Every Macintosh developer should have a copy of ResEdit, Apple’s resource editor application. It’s easy to use, indispensable, and best of all, free from your Apple dealer. Always get the latest version (2.1.1 at this writing), since it’s always being upgraded and improved. Beginners can get by without ResEdit, but you won’t want to.
For your information (recommended reading)
``````````````````````````````````````````
For any Macintosh programmer, we suggest you either own or have access to the entire series of “Inside Macintosh” technical reference guides by Addison Wesley. They are the definitive Macintosh bible for programmers of any caliber. They’re worth their weight in midnight oil if you want to get into serious Macintosh programming.
Another indispensable tool is THINK Reference, an on-line reference manual for C or Pascal programmers. It describes all the Mac’s data structures, variables, constants, functions and procedures. It also has valuable programming tips.
To program a Macintosh, you’ll have to know the basics of the Macintosh toolbox. We recommend the following:
• Get familiar with QuickDraw by reading chapter 6 of Inside Macintosh
Volume I (or equivalent). This section details drawing in the
Macintosh’s graphic environment.
• Get familiar with the Font Manager by reading chapter 7 of Inside
Macintosh Volume I (or equivalent). This section deals with drawing
text on the Macintosh’s screen
• Have a working knowledge of the Macintosh’s Memory Manager (chapter 3
of Inside Macintosh Volume I, or equivalent). This section deals with
pointers, handles, and memory fragmentation.
• The thing that differentiates a good Macintosh application from the
rest of the world is that a user will find the program easy to learn
and use. These benefits can be attributed greatly to a consistent and
well-designed user interface. Learn the dos and don’ts of graphic
user interface (GUI) design, then learn some more! Chapter 7 of
Inside Macintosh Volume I introduces you to the Macintosh’s GUI and
it’s standards. Another good way of learning is to get exposure to
(and become familiar with) a wide range of Macintosh applications.
You’ll spot the good ones and the not so good ones after a while!
